Подключение агента

Передайте данные агента и права, которые нужны для его первого профиля. project_id и role_id не передаются: проект определяется по подтверждающему человеку, роль выбирает backend во время одобрения.

Параметры запроса

• owner_email (string, обязательный) — e-mail подтверждающего пользователя, до 255 символов;
• agent_name (string, обязательный) — отображаемое имя агента, от 1 до 255 символов;
• agent_login (string, необязательный) — уникальный технический login, от 3 до 255 символов. Если не передать, backend сформирует его из имени и UUID запроса;
• permissions (string[], необязательный) — до 100 уникальных permissions с guard_name = user;
• purpose (string, необязательный) — назначение агента, до 5000 символов.

Пример запроса

{
	"owner_email": "owner@example.com",
	"agent_name": "Order Assistant",
	"agent_login": "agent-order-assistant",
	"permissions": [
		"view-orders",
		"view-counterparties"
	],
	"purpose": "Читать заказы и готовить сводки"
}

Ответ

{
	"message": "Если такой администратор есть, мы отправили запрос.",
	"request": {
		"public_id": "3f48862d-516d-4c7b-b486-9b7bb205f920",
		"request_token": "<request_token>",
		"expires_at": "2026-08-22T04:30:00+00:00"
	}
}

Сразу сохраните:

• request.public_id — публичный идентификатор процесса;
• request.request_token — секрет агентского клиента;
• request.expires_at — крайний срок одобрения и получения токена.

request_token не отправляется владельцу и не должен попадать в URL, логи или контекст модели.

Ответ 201 не гарантирует доставку письма. Gigma не раскрывает существование owner_email, а повторное письмо одному подтверждающему ограничено интервалом 10 минут. Не создавайте новый запрос сразу после успешного ответа.

Ошибки

• 422 — не прошла валидация поля или указано несуществующее permission;
• 429 — превышен лимит создания запросов.

Параметры пути

• publicId (string, обязательный) — UUID из ответа создания запроса.

Пример запроса

GET /api/agent-access-requests/3f48862d-516d-4c7b-b486-9b7bb205f920/review HTTP/1.1
Host: api.gigma.ru
Accept: text/html

Ответ

HTML-страница подтверждения. Секрет берётся из fragment ссылки и не должен передаваться в query string.

Параметры запроса

• approval_token (string, обязательный) — секрет из fragment ссылки.

Пример запроса

{
	"approval_token": "<approval_token>"
}

Ответ

{
	"status": "pending",
	"request": {
		"public_id": "3f48862d-516d-4c7b-b486-9b7bb205f920",
		"agent_name": "Order Assistant",
		"agent_login": "agent-order-assistant",
		"role": {
			"id": 14,
			"name": "employee"
		},
		"requested_permissions": [
			"view-orders",
			"view-counterparties"
		],
		"approved_permissions": null,
		"purpose": "Читать заказы и готовить сводки",
		"expires_at": "2026-08-22T04:30:00+00:00"
	}
}

Если approval_token передан в query string, backend возвращает 422. Неверный секрет маскируется как 404.

Параметры запроса

• approval_token (string, обязательный) — секрет подтверждения;
• permissions (string[], необязательный) — итоговое подмножество первоначально запрошенных permissions.

Если permissions не переданы, backend пытается одобрить весь запрошенный набор. Права, которых нет у подтверждающего пользователя, не удаляются автоматически: запрос вернёт 422.

Backend назначает роль employee, а для legacy-проекта — employer. Если подходящей роли нет или пользователь не вправе её назначить, ответ будет 422.

Пример запроса

{
	"approval_token": "<approval_token>",
	"permissions": [
		"view-orders",
		"view-counterparties"
	]
}

Ответ

{
	"status": "approved",
	"message": "Доступ одобрен. Агент может забрать токен."
}

Ошибки

• 404 — запрос или approval token не найден;
• 409 — запрос уже обработан либо истёк;
• 422 — permissions шире исходного запроса или недоступны подтверждающему.

Параметры запроса

• approval_token (string, обязательный) — секрет подтверждения.

Пример запроса

{
	"approval_token": "<approval_token>"
}

Ответ

{
	"status": "declined",
	"message": "Запрос доступа отклонён."
}

Параметры запроса

• request_token (string, обязательный) — секрет из ответа создания запроса.

Пример запроса

{
	"request_token": "<request_token>"
}

Ответ

{
	"status": "approved",
	"expires_at": "2026-08-22T04:30:00+00:00",
	"server_time": "2026-08-22T04:05:12+00:00"
}

Используйте интервал опроса не меньше 3–5 секунд. После 429 увеличьте интервал и учтите Retry-After, если заголовок присутствует.

Остановите опрос после declined, expired или consumed. После approved сразу переходите к consume.

request_token передаётся только в JSON body. Query string отклоняется с 422, неверный секрет возвращает 404.

Вызывайте endpoint только после статуса approved.

Параметры запроса

• request_token (string, обязательный) — секрет из ответа создания запроса.

Пример запроса

{
	"request_token": "<request_token>"
}

Ответ

Первый успешный ответ:

{
	"status": "consumed",
	"agent": {
		"id": 214,
		"name": "Order Assistant",
		"login": "agent-order-assistant"
	},
	"agent_token": {
		"id": 901,
		"name": "mcp-self-service",
		"value": "<agent_bearer>",
		"expires_at": "2027-08-22T04:05:20+00:00"
	}
}

agent_token.value показывается только в этом ответе. Сохраните его в хранилище секретов до завершения операции.

Повторный вызов возвращает только состояние:

{
	"status": "consumed",
	"already_consumed": true
}

Backend окончательно проверяет уникальность agent_login во время consume. Если login занят, ответ будет 409; изменить login в одобренном запросе нельзя — создайте новый запрос.

Перед созданием агента backend повторно проверяет подтверждающего пользователя и его проект. Временный 403 или конфликт проекта можно устранить и повторить consume, пока не истёк общий 30-минутный срок.